From aa9b9527b9e698550e2594b1561a8274c0cd576e Mon Sep 17 00:00:00 2001 From: X! Date: Mon, 17 Jan 2011 03:35:42 +0000 Subject: [PATCH] Add new Hooks class, because $wgHooks globals are evil. $wgHooks['EventName'][] = $callback; --> Hooks::register( 'EventName', $callback ); wfRunHooks( 'EventName', array() ); --> Hooks::run( 'EventName', array() ); Tests added to complement change. Backwards compatibility added. --- RELEASE-NOTES | 1 + includes/AutoLoader.php | 1 + includes/Hooks.php | 386 +++++++++++++++++++++++++--------------- 3 files changed, 243 insertions(+), 145 deletions(-) diff --git a/RELEASE-NOTES b/RELEASE-NOTES index e829726c1e..a520c8368b 100644 --- a/RELEASE-NOTES +++ b/RELEASE-NOTES @@ -49,6 +49,7 @@ it from source control: http://www.mediawiki.org/wiki/Download_from_SVN * New hook ArticlePrepareTextForEdit added, called when preparing text to be saved. * New parser option PreSaveTransform added, allows the pre-save transformation to be selectively disabled. +* Alternative to $wgHooks implemented, using the new Hooks class. === Bug fixes in 1.18 === * (bug 23119) WikiError class and subclasses are now marked as deprecated diff --git a/includes/AutoLoader.php b/includes/AutoLoader.php index d568aacc7b..be54fd6909 100644 --- a/includes/AutoLoader.php +++ b/includes/AutoLoader.php @@ -105,6 +105,7 @@ $wgAutoloadLocalClasses = array( 'HistoryBlobStub' => 'includes/HistoryBlob.php', 'HistoryPage' => 'includes/HistoryPage.php', 'HistoryPager' => 'includes/HistoryPage.php', + 'Hooks' => 'includes/Hooks.php', 'Html' => 'includes/Html.php', 'HTMLCacheUpdate' => 'includes/HTMLCacheUpdate.php', 'HTMLCacheUpdateJob' => 'includes/HTMLCacheUpdate.php', diff --git a/includes/Hooks.php b/includes/Hooks.php index 168f4bd9a5..4ccae327c5 100644 --- a/includes/Hooks.php +++ b/includes/Hooks.php @@ -35,172 +35,268 @@ * @param $args Array: parameters passed to hook functions * @return Boolean */ -function wfRunHooks($event, $args = array()) { +function wfRunHooks( $event, $args = array() ) { + return Hooks::run( $event, $args ); +} - global $wgHooks; +function hookErrorHandler( $errno, $errstr ) { + return Hooks::hookErrorHandler( $errno, $errstr ); +} - // Return quickly in the most common case - if ( !isset( $wgHooks[$event] ) ) { - return true; - } +class MWHookException extends MWException {} - if (!is_array($wgHooks)) { - throw new MWException("Global hooks array is not an array!\n"); - } - if (!is_array($wgHooks[$event])) { - throw new MWException("Hooks array for event '$event' is not an array!\n"); +/** + * Hooks class. + * + * Used to supersede $wgHooks, because globals are EVIL. + * + */ +class Hooks { + + protected static $handlers = array(); + + /** + * Attach an event handler to a given hook + * + * @access public + * @param mixed $name Name of hook + * @param mixed $callback Callback function to attach + * @return void + */ + public static function register( $name, $callback ) { + + if( !isset( self::$handlers[$name] ) ) { + self::$handlers[$name] = array(); + } + + self::$handlers[$name][] = $callback; + } - - foreach ($wgHooks[$event] as $index => $hook) { - - $object = null; - $method = null; - $func = null; - $data = null; - $have_data = false; - $closure = false; - $badhookmsg = false; - - /* $hook can be: a function, an object, an array of $function and $data, - * an array of just a function, an array of object and method, or an - * array of object, method, and data. - */ - - if ( is_array( $hook ) ) { - if ( count( $hook ) < 1 ) { - throw new MWException("Empty array in hooks for " . $event . "\n"); - } else if ( is_object( $hook[0] ) ) { - $object = $wgHooks[$event][$index][0]; - if ( $object instanceof Closure ) { - $closure = true; - if ( count( $hook ) > 1 ) { + + /** + * Returns true if a hook has a function registered to it. + * + * @access public + * @param mixed $name Name of hook + * @return bool + */ + public static function isRegistered( $name ) { + + if( !isset( self::$handlers[$name] ) ) { + self::$handlers[$name] = array(); + } + + return ( count( self::$handlers[$name] ) != 0 ); + + } + + /** + * Returns an array of all the event functions attached to a hook + * + * @access public + * @param mixed $name Name of hook + * @return array + */ + public static function getHandlers( $name ) { + + if( !isset( self::$handlers[$name] ) ) { + return array(); + } + + return self::$handlers[$name]; + + } + + + + + /** + * Call hook functions defined in Hooks::register + * + * Because programmers assign to $wgHooks, we need to be very + * careful about its contents. So, there's a lot more error-checking + * in here than would normally be necessary. + * + * @param $event String: event name + * @param $args Array: parameters passed to hook functions + * @return Boolean + */ + public static function run( $event, $args = array() ) { + + global $wgHooks; + + // Return quickly in the most common case + if ( !isset( self::$handlers[$event] ) && !isset( $wgHooks[$event] ) ) { + return true; + } + + if (!is_array(self::$handlers)) { + throw new MWException("Local hooks array is not an array!\n"); + } + + if (!is_array($wgHooks)) { + throw new MWException("Global hooks array is not an array!\n"); + } + + $new_handlers = (array) self::$handlers; + $old_handlers = (array) $wgHooks; + + $hook_array = array_merge( $new_handlers, $old_handlers ); + + if ( !is_array($hook_array[$event]) ) { + throw new MWException("Hooks array for event '$event' is not an array!\n"); + } + + foreach ($hook_array[$event] as $index => $hook) { + + $object = null; + $method = null; + $func = null; + $data = null; + $have_data = false; + $closure = false; + $badhookmsg = false; + + /* $hook can be: a function, an object, an array of $function and $data, + * an array of just a function, an array of object and method, or an + * array of object, method, and data. + */ + + if ( is_array( $hook ) ) { + if ( count( $hook ) < 1 ) { + throw new MWException("Empty array in hooks for " . $event . "\n"); + } else if ( is_object( $hook[0] ) ) { + $object = $hook_array[$event][$index][0]; + if ( $object instanceof Closure ) { + $closure = true; + if ( count( $hook ) > 1 ) { + $data = $hook[1]; + $have_data = true; + } + } else { + if ( count( $hook ) < 2 ) { + $method = "on" . $event; + } else { + $method = $hook[1]; + if ( count( $hook ) > 2 ) { + $data = $hook[2]; + $have_data = true; + } + } + } + } else if ( is_string( $hook[0] ) ) { + $func = $hook[0]; + if ( count( $hook ) > 1) { $data = $hook[1]; $have_data = true; } } else { - if ( count( $hook ) < 2 ) { - $method = "on" . $event; - } else { - $method = $hook[1]; - if ( count( $hook ) > 2 ) { - $data = $hook[2]; - $have_data = true; - } - } + throw new MWException( "Unknown datatype in hooks for " . $event . "\n" ); } - } else if ( is_string( $hook[0] ) ) { - $func = $hook[0]; - if ( count( $hook ) > 1) { - $data = $hook[1]; - $have_data = true; + } else if ( is_string( $hook ) ) { # functions look like strings, too + $func = $hook; + } else if ( is_object( $hook ) ) { + $object = $hook_array[$event][$index]; + if ( $object instanceof Closure ) { + $closure = true; + } else { + $method = "on" . $event; } } else { throw new MWException( "Unknown datatype in hooks for " . $event . "\n" ); } - } else if ( is_string( $hook ) ) { # functions look like strings, too - $func = $hook; - } else if ( is_object( $hook ) ) { - $object = $wgHooks[$event][$index]; - if ( $object instanceof Closure ) { - $closure = true; + + /* We put the first data element on, if needed. */ + + if ( $have_data ) { + $hook_args = array_merge(array($data), $args); } else { - $method = "on" . $event; + $hook_args = $args; } - } else { - throw new MWException( "Unknown datatype in hooks for " . $event . "\n" ); - } - - /* We put the first data element on, if needed. */ - - if ( $have_data ) { - $hook_args = array_merge(array($data), $args); - } else { - $hook_args = $args; - } - - if ( $closure ) { - $callback = $object; - $func = "hook-$event-closure"; - } elseif ( isset( $object ) ) { - $func = get_class( $object ) . '::' . $method; - $callback = array( $object, $method ); - } elseif ( false !== ( $pos = strpos( $func, '::' ) ) ) { - $callback = array( substr( $func, 0, $pos ), substr( $func, $pos + 2 ) ); - } else { - $callback = $func; - } - - // Run autoloader (workaround for call_user_func_array bug) - is_callable( $callback ); - - /* Call the hook. The documentation of call_user_func_array clearly - * states that FALSE is returned on failure. However this is not - * case always. In some version of PHP if the function signature - * does not match the call signature, PHP will issue an warning: - * Param y in x expected to be a reference, value given. - * - * In that case the call will also return null. The following code - * catches that warning and provides better error message. The - * function documentation also says that: - * In other words, it does not depend on the function signature - * whether the parameter is passed by a value or by a reference. - * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which - * is unsurprisingly marked as bogus. In short handling of failures - * with call_user_func_array is a failure, the documentation for that - * function is wrong and misleading and PHP developers don't see any - * problem here. - */ - $retval = null; - set_error_handler( 'hookErrorHandler' ); - wfProfileIn( $func ); - try { - $retval = call_user_func_array( $callback, $hook_args ); - } catch ( MWHookException $e ) { - $badhookmsg = $e->getMessage(); - } - wfProfileOut( $func ); - restore_error_handler(); - - /* String return is an error; false return means stop processing. */ - if ( is_string( $retval ) ) { - global $wgOut; - $wgOut->showFatalError( $retval ); - return false; - } elseif( $retval === null ) { + if ( $closure ) { - $prettyFunc = "$event closure"; - } elseif( is_array( $callback ) ) { - if( is_object( $callback[0] ) ) { - $prettyClass = get_class( $callback[0] ); - } else { - $prettyClass = strval( $callback[0] ); - } - $prettyFunc = $prettyClass . '::' . strval( $callback[1] ); + $callback = $object; + $func = "hook-$event-closure"; + } elseif ( isset( $object ) ) { + $func = get_class( $object ) . '::' . $method; + $callback = array( $object, $method ); + } elseif ( false !== ( $pos = strpos( $func, '::' ) ) ) { + $callback = array( substr( $func, 0, $pos ), substr( $func, $pos + 2 ) ); } else { - $prettyFunc = strval( $callback ); + $callback = $func; } - if ( $badhookmsg ) { - throw new MWException( "Detected bug in an extension! " . - "Hook $prettyFunc has invalid call signature; " . $badhookmsg ); - } else { - throw new MWException( "Detected bug in an extension! " . - "Hook $prettyFunc failed to return a value; " . - "should return true to continue hook processing or false to abort." ); + + // Run autoloader (workaround for call_user_func_array bug) + is_callable( $callback ); + + /* Call the hook. The documentation of call_user_func_array clearly + * states that FALSE is returned on failure. However this is not + * case always. In some version of PHP if the function signature + * does not match the call signature, PHP will issue an warning: + * Param y in x expected to be a reference, value given. + * + * In that case the call will also return null. The following code + * catches that warning and provides better error message. The + * function documentation also says that: + * In other words, it does not depend on the function signature + * whether the parameter is passed by a value or by a reference. + * There is also PHP bug http://bugs.php.net/bug.php?id=47554 which + * is unsurprisingly marked as bogus. In short handling of failures + * with call_user_func_array is a failure, the documentation for that + * function is wrong and misleading and PHP developers don't see any + * problem here. + */ + $retval = null; + set_error_handler( array( 'Hooks', 'hookErrorHandler' ) ); + wfProfileIn( $func ); + try { + $retval = call_user_func_array( $callback, $hook_args ); + } catch ( MWHookException $e ) { + $badhookmsg = $e->getMessage(); + } + wfProfileOut( $func ); + restore_error_handler(); + + /* String return is an error; false return means stop processing. */ + if ( is_string( $retval ) ) { + global $wgOut; + $wgOut->showFatalError( $retval ); + return false; + } elseif( $retval === null ) { + if ( $closure ) { + $prettyFunc = "$event closure"; + } elseif( is_array( $callback ) ) { + if( is_object( $callback[0] ) ) { + $prettyClass = get_class( $callback[0] ); + } else { + $prettyClass = strval( $callback[0] ); + } + $prettyFunc = $prettyClass . '::' . strval( $callback[1] ); + } else { + $prettyFunc = strval( $callback ); + } + if ( $badhookmsg ) { + throw new MWException( "Detected bug in an extension! " . + "Hook $prettyFunc has invalid call signature; " . $badhookmsg ); + } else { + throw new MWException( "Detected bug in an extension! " . + "Hook $prettyFunc failed to return a value; " . + "should return true to continue hook processing or false to abort." ); + } + } else if ( !$retval ) { + return false; } - } else if ( !$retval ) { - return false; } + + return true; } - - return true; -} - -function hookErrorHandler( $errno, $errstr ) { - if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) { - throw new MWHookException( $errstr ); + + //This REALLY should be protected... but it's public for compatibility + public static function hookErrorHandler( $errno, $errstr ) { + if ( strpos( $errstr, 'expected to be a reference, value given' ) !== false ) { + throw new MWHookException( $errstr ); + } + return false; } - return false; } - -class MWHookException extends MWException {} \ No newline at end of file -- 2.20.1